[% page.title = 'API Method: document items create'
   page.tab = 'api'
%]

<h2>POST /:user_id/documents/:folder_id/items/:item_id</h2>

<p>
Creates a document item in the specified documents folder of the specified user account.
Returns a representation of the created document item with a 201 Created HTTP status code.
To create multiple document items at once, see <a href="[% site.url %]/api/document-items-create-multiple">document items create (multiple)</a>.
</p>

<h3>URL:</h3>
<code>[% site.url %]/<em>user_id</em>/documents/<em>folder_id</em>/items/<em>item_id</em>.<em>format</em></code>

<h3>Formats (<a href="formats">about return formats</a>):</h3>
<code>[% INCLUDE 'api/_formats.phtml' %]</code>

<h3>HTTP Methods (<a href="http-methods">about HTTP methods</a>):</h3>
<code>POST</code>

<h3>Requires Authentication (<a href="authentication">about authentication</a>):</h3>
<code>true</code>

<h3>Parameters:</h3>
<ul>
<li><code>folder_id</code>.  Required. The ID of the documents folder to create the document item in.</li>
<li><code>item_id</code>.  Required. The ID of the document item to create.</li>
<li><code>text</code>.  Required. The text of the document item.</li>
<li><code><em>description</em></code>.  Optional. The description of the document item.</li>
<li><code><em>full</em></code>.  Optional. Whether to include the <code>text</code> data in the returned representation of the item.
Values can be either <code>1</code> for true or <code>0</code> for false. The default is <code>0</code>.
<ul>
<li>Example: <code>[% site.url %]/kdd09/documents/pc/items/Peter%20Flach.xml</code><br/>
<code>text=roc curves logic structured data mining machine learning</code><br/>
</li>
</ul>
</li>
</ul>


<h3>Usage Examples:</h3>
<blockquote>
<h4>cURL (<a href="curl">about cURL</a>):</h4>
<code>curl -X POST -H "Token:mytoken" -d "text=roc curves logic structured data mining machine learning"<span class="cr"></span><br/>
-d "description=Some research interests of Peter Flach"<span class="cr"></span><br/> 
-d "full=1" [% site.url %]/kdd09/documents/pc/items/Peter%20Flach</code><br/>
</blockquote>

<h3>Response (<a href="return-values">about return values</a>):</h3>
<blockquote>
<h4>XML example:</h4>
<pre>[% FILTER html -%]
<?xml version="1.0" encoding="UTF-8"?>
<result>
  <item>
    <name>Peter Flach</name>
    <created>1278025168</created>
    <description>Some research interests of Peter Flach</description>
    <id>Peter_Flach</id>
    <modified>1278025168</modified>
    <source>text</source>
    <text>roc curves logic structured data mining machine learning</text>
  </item>
</result>
[% END %]</pre>
</blockquote>

